home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / utils / 2obj110 / 2obj.doc < prev    next >
Text File  |  1994-01-07  |  20KB  |  555 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.        2OBJ - Binary to OBJ File Converter.
  7.        ====================================
  8.  
  9.  
  10.        Version 1.10
  11.  
  12.        (c) 1993 Mark Thomas
  13.  
  14.        NPS Software.
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.    Contents.
  22.    =========
  23.  
  24.    Description
  25.    Copyright and Licence
  26.    Using 2OBJ
  27.    Limitations
  28.    Release History
  29.    References
  30.    About the Author
  31.  
  32.  
  33.    Description.
  34.    ============
  35.  
  36.    2OBJ is a program that can create an object (.OBJ) file from binary
  37.    files so that they can be linked directly into a program along with
  38.    compiled source code and other data.  It provides a smaller, faster
  39.    and more secure alternative to the traditional methods of including
  40.    data files in programs.   Firstly  2OBJ  eliminates  the  need  for
  41.    external  data files to accompany the main program, as all the data
  42.    can be included directly inside the final EXE file.  It  is  faster
  43.    than  the normal time consuming method of including binary files in
  44.    a program; translating it into source code  as  a  large  character
  45.    array which must then converted back into data by the compiler.
  46.  
  47.    Features :
  48.  
  49.    ■ Decodes CEL, PCX, LBM and GIF files and their VGA palettes.
  50.  
  51.    ■ Generates OBJ file dependency information for MAKE utilities.
  52.  
  53.    ■ Splits files that are greater than 64k into multiple segments.
  54.  
  55.    ■ Full C source code is included.
  56.  
  57.  
  58.    Copyright and Licence.
  59.    ======================
  60.  
  61.    2OBJ  is  supplied  for  personal,  private  use.   Feel  free   to
  62.    distribute  the  program as long as it is supplied in its original,
  63.    unmodified form, which includes this documentation.
  64.  
  65.    You may NOT re-distribute modified versions of the source code  nor
  66.    distribute  the  source  code  for  a  profit.   If  you  make  any
  67.    worthwhile changes to the source code, you can send them to me  for
  68.    inclusion in a future release.
  69.  
  70.    Since this software is free, it is supplied "AS  IS",  WITHOUT  ANY
  71.    WARRANTY;  without  even the implied warranty of MERCHANTABILITY or
  72.    FITNESS FOR A PARTICULAR PURPOSE. It is supplied as is, in the hope
  73.    the people will find it useful.
  74.  
  75.  
  76.    Using 2OBJ.
  77.    ===========
  78.  
  79.    Usage:
  80.  
  81.    2OBJ filetype [switches] infile [outfile[.OBJ | .BIN]] segspecs
  82.  
  83.    filetype :
  84.  
  85.    This character determines how 2OBJ treats the input file,  it  also
  86.    sets the input file extension default.
  87.  
  88.    B : Binary, this of course can be any file, I have  used  2OBJ  for
  89.        such  things  as  compressed help data, text files, sin tables,
  90.        ANSI screens, fonts, and MOD files.
  91.  
  92.    C : AutoDesk Animator CEL files.
  93.  
  94.    G : Compuserve GIF files.
  95.  
  96.    L : DeluxePaint LBM files.
  97.  
  98.    P : PCPaintbrush PCX files.
  99.  
  100.    V VGA palette, 2OBJ can extract the palette from any of the graphic
  101.        file formats it supports.
  102.  
  103.    switches :
  104.  
  105.    /C Adds an underscore (_) to the symbol name.
  106.  
  107.        Most PC C compilers add a  leading  underscore  to  all  public
  108.        symbols  (I  cannot  remember  the  reason  why),  this  switch
  109.        provides an alternative to typing it directly.
  110.  
  111.    /Hsize, /Tsize Removes a header/tail of size bytes  from  a  binary
  112.        input file.
  113.  
  114.        The header and tail functions allow the size of the binary file
  115.        to be adjusted.  The size is an unsigned decimal long string.
  116.  
  117.    /H[+|-] Include or exclude(default) the header of a graphics file.
  118.  
  119.        By default 2OBJ will leave off the header of the graphics  file
  120.        and write ONLY the compressed image data to the OBJ file.  This
  121.        is because in most circumstances the size  of  the  screen  and
  122.        image  will  be  constant  and the information in the header is
  123.        unnecessary.  With the header included the  entire  input  file
  124.        will  be  included,  the same result as if the binary file type
  125.        had been used.
  126.  
  127.    /V Verbose mode, display extra information.
  128.  
  129.        Mainly for  debugging  and  checking,  displays  extra  warning
  130.        messages  and  file statistics.  For graphics files information
  131.        about the bitmap is displayed.
  132.  
  133.    /L Convert all symbols to lowercase.
  134.  
  135.        Counterpart to the /U switch but that  is  about  all,  totally
  136.        useless.
  137.  
  138.    /S Split large (>64k) input files.
  139.  
  140.        Multiple segments can be created  to  handle  input  files  (or
  141.        decoded  bitmaps)  larger than the segment limit of 64k.  These
  142.        (if linked together in the correct  order)  will  recreate  the
  143.        binary  data  in a contiguous region of memory.  This is not to
  144.        be confused with 386 32 bit segments  which  can  have  a  4Gig
  145.        limit,  2OBJ  does  not  support  this  in  any way.  2OBJ will
  146.        produce up to 10 segments, so the maximum  size  of  the  input
  147.        file is 640k.
  148.  
  149.    /U Convert all symbols to uppercase.
  150.  
  151.        Pascal and Assembler (if none of the /Mx switches are used) are
  152.        case  insensitive  and  convert all their symbols to uppercase.
  153.        By  default  2OBJ  will  preserve  the  case  of  the   symbols
  154.        characters  as  they are on the command line.  In any case both
  155.        the /U and /L need never be used  as  the  linker  is  normally
  156.        responsible  for matching symbol names and will convert them as
  157.        necessary.
  158.  
  159.    /X Disables output of .OBJ file when using /D.
  160.  
  161.        This switch gives 2OBJ another utility  purpose,  it  generates
  162.        the decoded bitmap that is normally the temporary 2OBJ decoding
  163.        file as a binary file containing the bitmap data.  No OBJ  file
  164.        is created.
  165.  
  166.    /D Decode file type.
  167.  
  168.        This switch forces 2OBJ to decode the graphics file or palette.
  169.  
  170.        Note: 2OBJ simply decodes the files bitmap, so the output  data
  171.        is  dependant  on how the file format organises the pixel data.
  172.        Generally all 256 colour files will produce  the  same  output,
  173.        regardless of the file type.
  174.  
  175.        GIFs use a byte for each pixel values.  Each pixel in the image
  176.        has  a  byte value, no matter what number of colours there are.
  177.        So a  decoded  monochrome  GIF  will  have  width*height  bytes
  178.        containing  nothing  more  than 0 or 1 values.  Decoding leaves
  179.        interleaved lines interleaved.
  180.  
  181.        PCX files match the video memory organisation for the mode they
  182.        were  created  on,  planar  for mono and 16 colours and not for
  183.        256.
  184.  
  185.        LBM files are interesting, the PC version of DeluxePaint has an
  186.        extension  to the file format called PackedBitMap to handle the
  187.        fact that the VGA 256 colour mode is not planar (where  as  all
  188.        Amiga  modes  are).   It  is  still  possible to generate a 256
  189.        planar bitmap by saving the file with  a  stencil  active,  but
  190.        2OBJ will not be able to decode this properly.  The output of a
  191.        decoded LBM is identical to PCX.  2OBJ cannot decode LBM  files
  192.        when  a  mask  defined,  so  the  output  for  images  saved in
  193.        DeluxePaint when a stencil  was  enabled  or  brushes  will  be
  194.        incorrect.
  195.  
  196.        CELs are the simplest file format because, as far  as  I  know,
  197.        they  support  only  256 colour images and have no compression.
  198.        The CEL file type can also be  used  to  handle  the  temporary
  199.        ".PIC"  files  AutoDesk  Animator  generates.   The decode (/D)
  200.        option is superfluous with CELs because they are not compressed
  201.        or encoded.
  202.  
  203.        The decode switch can also be used  with  palettes  to  convert
  204.        them to VGA colour register hardware values.
  205.  
  206.        ** Note: All formats except CELs store the palette as 8 bit  **
  207.        ** values which will not correctly work with the 6 bit VGA   **
  208.        ** hardware levels.  Using the /D decode option 2OBJ will    **
  209.        ** scale down the values so they can be used directly.       **
  210.  
  211.  
  212.    infile   :   Input   file,   the   extension   will   default    to
  213.        BIN/CEL/PCX/GIF/LBM to match the file type.
  214.  
  215.  
  216.    outfile : Output  file,  this  is  optional  and  will  default  to
  217.        infile.OBJ, or infile.BIN when the /X option is used.
  218.  
  219.  
  220.    segspecs : Segment specifications.
  221.  
  222.        These are not required when the /X option is used.   There  are
  223.        two  ways  to specify a segment, the simplified model directive
  224.        or a complete assembler style segment definition.
  225.  
  226.         [group:]SEGNAME:[align:]['class':]SYMBOL
  227.                 align = [BYTE | WORD | PARA | PAGE]
  228.  
  229.        The default group is none defined,  the  default  alignment  is
  230.        PARA  and  there  is no default class string.  All segments are
  231.        defined as public.  There MUST be single quote  (')  characters
  232.        around the class string.
  233.  
  234.         .model:SYMBOL
  235.                 model = [TINY|SMALL|MEDIUM|COMPACT|LARGE|HUGE]
  236.  
  237.        The .model generates a full  segment  specification  as  above.
  238.        The segment specifications generated are:
  239.  
  240.                         Group   Name        Align Class   Combine
  241.  
  242.         .TINY           DGROUP  _DATA       WORD  'DATA'  PUBLIC
  243.         .SMALL          DGROUP  _DATA       WORD  'DATA'  PUBLIC
  244.         .MEDIUM         DGROUP  _DATA       WORD  'DATA'  PUBLIC
  245.         .COMPACT                name_DATA   PARA  'DATA'  PRIVATE
  246.         .LARGE                  name_DATA   PARA  'DATA'  PRIVATE
  247.         .HUGE                   name_DATA   PARA  'DATA'  PRIVATE
  248.  
  249.        Where 'name' is the name of the input file.
  250.  
  251.        Groups are used to collect several  segments  together  into  a
  252.        single  segment  and  allows  the  data in those segments to be
  253.        accessed relative to the start of the group.  The  segments  in
  254.        groups do not need to belong to the same class or have the same
  255.        combine type, however they must all fit within 64K.
  256.  
  257.        The alignment tells the linker to ensure the segment begins  on
  258.        the  specified  boundary.   As  the  linker  processes each new
  259.        segment when  building  the  output  EXE  file  it  checks  the
  260.        alignment type of the segment and if necessary will pad out the
  261.        difference with null bytes.
  262.  
  263.        The segment class is a string which is used by  the  linker  to
  264.        combine segments when building the output EXE file.  The linker
  265.        will group together all PUBLIC segments  with  the  same  class
  266.        name.
  267.  
  268.        The segment combine type is used by the linker whether  two  or
  269.        more  segments  should  be  combined  into  a  larger  segment.
  270.        PRIVATE segments will not be combined with any  other  segments
  271.        of  the  same  name, while PUBLIC segments will be concatenated
  272.        with other segments of the same name and class to form a single
  273.        larger segment.  2OBJ does not allow the combine type to be set
  274.        and defines all segments as public.  The exception is when 2OBJ
  275.        splits a large file, when it generates several private segments
  276.        64k in length.
  277.  
  278.        There  are  several  rules  that  linkers  follow  to   combine
  279.        segments.  Firstly only segments that have the public or common
  280.        type will be combined into  a  single  larger  segment.   If  a
  281.        segment  has  a  public  combine type, the linker automatically
  282.        combines it with other segments that have  the  same  name  and
  283.        belong  to  the  same class.  The resulting combined segment is
  284.        treated as if the smaller segments were  defined  in  it  as  a
  285.        whole.
  286.  
  287.        Link will normally place segments in the executable file in the
  288.        same order that it encounters them in the objects files.
  289.  
  290.        When interfacing with a high level such as C or Pascal only the
  291.        simplified  .model  specifier should ever be needed.  Assembler
  292.        allows either option to be used, depending on how the  segments
  293.        are defined in the ASM source code.
  294.  
  295.        If the data generated by 2OBJ seems to be incorrect  there  are
  296.        several  ways  to verify it, the best option is to use the /MAP
  297.        (or equivalent) option of your linker to generate  a  map  file
  298.        which  lists  all  segments  and public symbols in the program.
  299.        Alternatively there are several shareware programs  ReadOBJ  or
  300.        OBJTool or  commercially  Borland's  TDump  which can provide a
  301.        descriptive dump of the OBJ file.  Lastly a simple binary  file
  302.        viewer  can  be used to check the names and the data in the OBJ
  303.        and  EXE  files.   Typical  problems  are  unexpected   segment
  304.        combines made the linker, and segments exceeding the 64k limit.
  305.        The best solution to this is to give each  segment  you  create
  306.        with 2OBJ a unique class name.
  307.  
  308.    All  error  and  warning  messages  generated  by  2OBJ  are   self
  309.        explanatory.
  310.  
  311.  
  312.    Linking to languages.
  313.    =====================
  314.  
  315.    These examples assume a 320x200x256 graphic file called testpic.XXX
  316.    is   available   in  the  current  directory  (where  .XXX  is  the
  317.    appropriate file extension).  The file  type  option  in  the  2OBJ
  318.    command  line  examples should be changed to match that of the file
  319.    type being used (in the examples I used a PCX file, filetype  'p').
  320.    The  example  programs  also require a VGA, although the palette of
  321.    the  graphic  file  is  not  displayed,  so  the  colours  will  be
  322.    incorrect, unless the image uses the default VGA palette.
  323.  
  324.  
  325.    Assembler.
  326.  
  327.    Tested with Tasm 3.0 and Masm 5.1
  328.  
  329. 2OBJ p /d testpic _BITMAP_DATA:PARA:'BITMAP_DATA':Bitmap
  330. link test.obj testpic.obj;
  331.  
  332. ----
  333.  
  334. _BITMAP_DATA    SEGMENT PARA PUBLIC 'BITMAP_DATA'
  335.         Extrn   Bitmap:BYTE
  336. _BITMAP_DATA    ENDS
  337.  
  338.  
  339. _CODE   SEGMENT PARA PUBLIC 'CODE'
  340.  
  341. Main:
  342.         mov     ax,0013h
  343.         int     10h
  344.  
  345.         mov     ax,_BITMAP_DATA
  346.         mov     ds,ax
  347.         mov     ax,0A000h
  348.         mov     es,ax
  349.  
  350.         xor     di,di
  351.         mov     si,di
  352.         mov     cx,64000/2
  353.         rep     movsw
  354.  
  355.         mov     ah,0
  356.         int     16h
  357.  
  358.         mov     ax,04C00h
  359.         int     21h
  360. _CODE   ENDS
  361.  
  362. END     Main
  363. ----
  364.  
  365.    C.
  366.  
  367.    The OBJ file created by 2OBJ can be added in the  command  line  of
  368.    the  linker, if you are compiling from the command line. If you use
  369.    an IDE; in Turbo C, simply list  the  file  in  the  project,  with
  370.    Microsoft  C  and  QuickC  the OBJ file must be included in the MAK
  371.    file.
  372.  
  373.    Tested with QuickC 2.0, requires Compact/Large/Huge memory model.
  374.  
  375. 2OBJ p /d testpic .large:_Bitmap
  376.  
  377. ----
  378.  
  379. extern char Bitmap[];
  380.  
  381. main()
  382. {
  383.         _asm {
  384.                 mov     ax,0013h
  385.                 int     10h
  386.         }
  387.  
  388.  
  389.         memcpy((char *)0xA0000000L, Bitmap, 64000);
  390.  
  391.         getch();
  392.  
  393.         _asm {
  394.                 mov     ax,0003h
  395.                 int     10h
  396.         }
  397. }
  398. ----
  399.  
  400.    TurboPascal.
  401.  
  402.    Pascal does not allow initialised data  is  to  be  defined  within
  403.    object files, however it does allow procedures to be defined in OBJ
  404.    files.  Although Bitmap is defined as  a  procedure  you  MUST  NOT
  405.    execute  it.   It  contains only data which must be referred to via
  406.    pointers.
  407.  
  408.  
  409.    Tested with TurboPascal 7.0
  410.  
  411. 2OBJ p /d testpic CODE:WORD:Bitmap
  412.  
  413. ----
  414. uses  crt;
  415.  
  416. {$L TESTPIC.OBJ }
  417. procedure Bitmap; external;
  418.  
  419. begin
  420.  
  421.      inline(
  422.             $B8/$13/$00/        (* mov ax,$0013 *)
  423.             $CD/$10             (* int $10 *)
  424.      );
  425.  
  426.  
  427.      Move (pointer(@Bitmap)^,ptr($A000,0)^,64000);
  428.  
  429.      ReadKey;
  430.  
  431.      inline(
  432.             $B8/$03/$00/        (* mov ax,$0013 *)
  433.             $CD/$10             (* int $10 *)
  434.      );
  435.  
  436. end.
  437. ----
  438.  
  439.    QuickBasic
  440.  
  441.    It is apparently also possible to use OBJ files with QuickBasic  in
  442.    a  manner  similar to that required with Pascal, but I have no idea
  443.    how this is done.
  444.  
  445.  
  446.    Limitations.
  447.    ============
  448.  
  449.    None of the graphics file formats are totally  supported  (although
  450.    most of the exceptions are not in common use) :
  451.  
  452.    ■ Cannot properly decode LBM  files  that  have  a  mask  (stencil)
  453.    defined   unfortunately   this   includes   brush  files  saved  by
  454.    DeluxePaint.
  455.    ■ It is unlikely that 2OBJ can handle LBM files that  were  created
  456.    on an Amiga.
  457.    ■ Does not support GIF files with  multiple  images  or  extensions
  458.    blocks.
  459.    ■ Support for 24 bit variations of GIF or PCX is untested.
  460.    ■ CEL support is based only  on  viewing  CEL  files  with  a  file
  461.    editor.
  462.  
  463.    [2OBJ has been tested with  files  from  DeluxePaint  II  Enhanced,
  464.    Autodesk Animator, Windows 3.1 Paint and Improces 4.0]
  465.  
  466.  
  467.    Release History.
  468.    ================
  469.  
  470.    1.00  21-05-92   Originally two programs; PCX2OBJ and BIN2OBJ written to
  471.                         support a loader, these sat on my hd for a while
  472.                         undergoing various changes when I required them and
  473.                         eventually evolved into 2OBJ.
  474.  
  475.    1.10  08-12-93   First public release.
  476.  
  477.  
  478.    References.
  479.    ===========
  480.  
  481.    ■ MS-DOS Encyclopedia, MS Publishing
  482.    Provides a detailed specification of the OBJ file format.
  483.  
  484.    ■ WASP 2.00b Source by Steven Reiz.
  485.    An Amiga graphic file conversion program, the basis for LBM support.
  486.  
  487.    ■ GIF source by Steven A. Bennett
  488.  
  489.  
  490.    About the Author.
  491.    =================
  492.  
  493.    ■ Mark Thomas is a 21 year old graduate in  Information  Technology
  494.    and  is  currently  seeking  employment [subtle hint to prospective
  495.    employers].
  496.  
  497.    ■ Member of the Sivris demo group who have  recently  released  our
  498.    first  demo  'Divide  by  Zero'  and  are  now  starting our second
  499.    'Information Generation'.
  500.  
  501.    ■ Member of NPS Internationalé who are not doing much at all at the
  502.    moment.
  503.  
  504.    ■ Author of the "soon to be released" MegaDebugger [MMD],  see  the
  505.    advert at the end of this file.
  506.  
  507.  
  508.    I would appreciate any comments/suggestions you may  wish  to  make
  509.    about  2OBJ.  Also if you make any significant modifications to the
  510.    source I would like to receive them to be incorporated in the  next
  511.    release  (particularly  more  file  formats).   I  myself  have  no
  512.    particular plans for 2OBJ at the moment, as  it  is  working  quite
  513.    well  for  my  purposes.  You are welcome to use any my routines in
  514.    your own programs as long as there is some credit/mention  made  to
  515.    their original author.
  516.  
  517.  
  518.    FidoNet:
  519.    3:640/450
  520.  
  521.    BBS:
  522.    The Farmer's BBS
  523.    +61 76 916258
  524.  
  525.    No Net Address:
  526.  
  527.    Mark Thomas
  528.    8 Herronbee Street
  529.    Toowoomba, Queensland
  530.    Australia  4350.
  531.  
  532.    InterNet:
  533.  
  534.    I wish!
  535.  
  536.  
  537.    ┌─────────────────────────────────────────────────────────────────┐
  538.    │ <MMD> Mark's MegaDebugger.  Full screen debugger for the 80x86. │
  539.    │─────────────────────────────────────────────────────────────────│
  540.    │                                                                 │
  541.    │ Features:                                                       │
  542.    │ ■ Register level screen swapping: saves and restores "mode-x",  │
  543.    │    screens, split screens, palettes and screen memory perfectly.│
  544.    │ ■ C, Pascal, Assembler and A86 expression support.              │
  545.    │ ■ Windowed display with EGA/VGA 25, 28, 43 and 50 line support. │
  546.    │ ■ Conditional breakpoints and watchpoints (global breakpoints). │
  547.    │ ■ Displays memory allocation, open files and interrupt usage.   │
  548.    │ ■ Keyboard keeper, can always detect break-key presses.         │
  549.    │ ■ Completely configurable (keys, colours, options).             │
  550.    │ ■ Online context sensitive help.                                │
  551.    │ ■ Uses only 20k-50k memory.                                     │
  552.    └─────────────────────────────────────────────────────────────────┘
  553.  
  554. -end-
  555.